<!-- Links to Codesite stylesheet; for help in editing/previewing article only -->

<link href="http://code.google.com/css/base-200606.css" type="text/css" rel="stylesheet"/>
<link href="http://code.google.com/css/homepage.css" rel="stylesheet" type="text/css"/>

<!-- Article Begins -->
<h1>Codelab: Taking Content Offline With Gears Using PubTools</h1>
<em>Brad Neuberg, Google Developer Programs
<br>May 2008</em>

<ul>
  <li><a href="#introduction">Introduction</a></li>
  <li><a href="#prerequisites">Prerequisites</a></li>
  <li><a href="#codelab">Codelab</a></li>
</ul>

<h2 id="introduction">Introduction</h2>
<p class="para">
<a href="http://gears.google.com">Google Gears</a> is an open source plug-in 
that teaches current web browsers new tricks. 
Gears is a clever way to raise the bar cross-browser and cross-platform, 
running inside of Firefox and Internet Explorer on Windows, Mac OS X, and Linux. 
APIs include: A real embedded relational database (SQLite) for web sites; 
client-side full text search; threads for JavaScript; offline web applications; 
secure and fast cross-domain mashups; desktop shortcuts; mobile devices; 
and more.
</p>

<p class="para">
Gears PubTools is a simple collection of JavaScript files that make it easy for
content authors to work with Google Gears without having to delve into 
JavaScript themselves. With PubTools, you can easily offline-enable your 
content within minutes:
</p>
  
<ul>
<li>Point to a Gears manifest file with a simple HTML attribute:<br>

<pre>
&lt;html gears-manifest="manifest.js"&gt;
</pre>
</li>

<li>Create a shortcut desktop shortcut icon that points right to your app and
use a custom image:<br>

<pre>
&lt;html shortcut="true" gears-manifest="manifest.js">
  &lt;head>
    &lt;link rel="shortcut.icon" title="32x32" href="icon32x32.png"&gt;&lt;/link&gt;
</pre>
</li>    

<li>You don't even have to write the manifest file yourself! PubTools includes 
a simple bookmarklet that developers can drag to their browser's toolbar. 
Just navigate to the web pages you want offline, press the "Generate Manifest"
bookmarklet, and a dialog will appear with the full manifest file generated 
for you ready to cut and paste into a file.</li>

</ul>

<p class="para">
This article includes a simple codelab that steps you through adding 
Gears PubTools to your own web page.</p>

<p class="para">Please note that Gears PubTools is not part of the official 
Google Gears distribution. The project home for the open source Gears
PubTools project is at 
<a href="http://code.google.com/p/gears-pubtools/">http://code.google.com/p/gears-pubtools/</a>.
The full quick start guide and documentation on Gears PubTools is available
<a href="http://gears-pubtools.googlecode.com/svn/trunk/README.txt">here</a>.
You can see a full example demo page filled out using Gears PubTools 
<a href="http://gears-pubtools.googlecode.com/svn/trunk/demos/demo.html">here</a>.
</p>

<h2 id="prerequisites">Prerequisites</h2>

<p class="para">To run this codelab, you must have a local web server installed.
The codelab below will not work if you try to load and create it from your
local file system using <code>file://</code> URLs.</p>

<p class="para">A good choice is 
  <a href="http://httpd.apache.org/download.cgi">Apache</a>. Download
  Apache and install it; if you are using Linux or
  Mac OS X it is most likely already present. Apache generally has a 
  directory where all content is served from:</p>
  
<ul>
  <li>On Linux it is generally in <code>/var/www</code></li>
  <li>On Mac OS X it is generally in <code>/Library/WebServer</code></li>
  <li>For Windows, identify where you installed Apache and find the
    <code>htdocs</code> folder inside of here</li>
</ul>

<p class="para">Start Apache and confirm that it works by visiting
  <code>http://localhost</code>.</p>
  
<p class="para">You must also have Gears 0.3+ installed for this codelab.
  Navigate to the <a href="http://gears.google.com">Gears Install Page</a>.
  If Gears is installed, confirm that the version is 0.3 or higher; if it
  is not, press the Upgrade button. Otherwise press Install to install
  Gears if it is not present.</p>
  
<p class="para">Please note that only Firefox and 
  Internet Explorer are currently supported for Gears; you can not use Safari
  or Opera for the following codelab. 64-bit Linux is also not currently
  supported. Firefox 3 support is under development and will be available
  soon, but will not work with the codelab below with Gears currently.</p>

<h2 id="codelab">Codelab</h2>

<p class="para">In this codelab we will be taking an example page offline,
  plus its CSS and images, using PubTools and without needing to know
  JavaScript:</p>

<ul>
  <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/demo.html">Before page</a> - Does not have PubTools</li>
  <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/after/demo.html">After page</a> - Has PubTools in the page</li>
</ul>  
  
  <p class="para">Notice the 'Download Offline' link in the after page; when
  pressed, the page's content will be downloaded and a shortcut icon will
  be dropped on to the desktop so you can quickly access this content
  when offline.</p>
  
  <p class="para">If you ever run into issues or need help, you can
    'cheat' by looking at the source of the 
    <a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/after/demo.html">after</a> page.</p>
  
<ol> 
  
<li>Save the 
  <a href="http://gears-pubtools.googlecode.com/svn/trunk/src/pubtools-gears.js">following JavaScript</a>
  to your file system by right-clicking and choosing "Save As...". 
  Name the file <code>pubtools-gears.js</code>.</li>

<li>Download the following files and give them the following names; make sure
  to save these into the directory your local web server serves from:
  <ul>
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/pubtools-gears.js">pubtools-gears.js</a></li>
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/demo.html">demo.html</a></li>
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/demo.css">demo.css</a></li>    
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/balloon.jpg">balloon.jpg</a></li>
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/icon128x128.png">icon128x128.png</a></li>
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/icon48x48.png">icon48x48.png</a></li>
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/icon32x32.png">icon32x32.png</a></li>
    <li><a href="http://gears-pubtools.googlecode.com/svn/trunk/codelabs/codelab1/before/icon16x16.png">icon16x16.png</a></li>
  </ul>
</li>

<li>Edit <code>demo.html</code> and add a <code>script</code> tag to load
  up <code>pubtools-gears.js</code>. <code>pubtools-gears.js</code> is the
  JavaScript file for PubTools and must be included into your web page
  for PubTools to work.</li>

<li>Go to 
  <a href="http://gears-pubtools.googlecode.com/svn/trunk/src/manifest-bookmarklet.html">this page</a> 
  and add the manifest generator bookmarklet by following the instructions on that page.</li>
  
<li>Navigate to the <code>demo.html</code> file you have locally, and press 
  the manifest bookmarklet you just setup to generate the manifest file.
  (If you are interested, 
  <a href="http://code.google.com/apis/gears/api_localserver.html#manifest_file">learn more about Gears manifest files</a>).</li>

<li>Save the generated manifest file that appears on your screen in the
  DHTML popup window into a new file, named <code>manifest.js</code></li>
  
<li>Edit <code>demo.html</code> and add a <code>gears-manifest="manifest.js"</code>
  attribute pointing to your newly generated manifest file onto the top <code>html</code>
  tag.</li>
  
<li>Add <code>&lt;div id="gears-pubtools-offline-widget"&gt;&lt;/div&gt;</code> into 
  the web page where you want the Gears PubTools <code>Download Offline</code>
  link to appear.</li>
  
<li>PubTools can optionally create a shortcut on the user's desktop
  for the bundle of content you want to take offline. Add <code>shortcut="true"</code>
  to the root <code>html</code> tag in <code>demo.html</code>.</li>

<li>You must provide at least one icon in PNG format for your desktop icon; possible sizes are 
16x16, 32x32, 48x48, 128x128. Providing all of them is best to allow the OS 
to choose the best one. Specify them using a <code>link</code> tag in
your HTML file, in the <code>head</code> section; we will simply use the
example icons we downloaded earlier:<br>

<pre>
&lt;link rel="shortcut.icon" title="16x16" href="icon16x16.png"&gt;&lt;/link&gt;
&lt;link rel="shortcut.icon" title="32x32" href="icon32x32.png"&gt;&lt;/link&gt;
&lt;link rel="shortcut.icon" title="48x48" href="icon48x48.png"&gt;&lt;/link&gt;
&lt;link rel="shortcut.icon" title="128x128" href="icon128x128.png"&gt;&lt;/link&gt;
</pre>

<p class="para">Make sure your HTML document has a <code>title</code> element;
  the default text on the shortcut icon will come from the <code>title</code>.
  The <code>demo.html</code> file already has a <code>title</code>
  so you don't need to do anything for this example.</p>

<p class="para">By default, PubTools chooses intelligent defaults for the shortcut icon. 
For this codelab simply use the defaults. For reference, however, you can 
override these if you wish using <code>meta</code> tags:</p>

<pre>
&lt;meta name="shortcut.name" content="Test Application"&gt;&lt;/meta&gt;
&lt;meta name="shortcut.description" 
  content="An application at http://www.test.com/index.html"&gt;&lt;/meta&gt;
&lt;meta name="shortcut.url" content="http://www.test.com/index.html"&gt;&lt;/meta&gt;
</pre>     
          
<p class="para">Most of these have sensible defaults and can be left out:
<code>shortcut.name</code> defaults to the HTML <code>title</code> element if not present.
<code>shortcut.url</code> defaults to the page's URL if not present.
<code>shortcut.description</code> is optional and defaults to the string
"Offline Web Application"</p>
</li>

<li>You're done!</li>

</ol>

<p class="para">To test, load your modified <code>demo.html</code> page. You should see the 
"Download Offline" link appear in your page. If it does not, something
was done wrong in one of the previous tests. Click this link. You
should be prompted by Gears on whether you want to give permission to add a 
desktop icon. Press Yes. Gears PubTools will then download your content
offline. Go to File > Work Offline in your web browser. If you reload
the page you should see the content you offline enabled appear. Users
can access this content even if the network is gone or the content is
not in the browser's cache. If you look at your desktop, you should see
a new icon on your desktop (the example icon is a black and white
photo of hot air balloons). Double click this to access your offline
content whether the network is present or not.</p>

<p class="para">This was a pretty simple example; in the real world, you could
  take a large bundle of documentation or tutorials, such as technical
  documents, and offline enable them for quick reference.</p>
<!-- Article Ends -->

